# Incido — Development Plan

## 0. Project Overview

**Name:** Incido (Latin, pronounced "een-chi-do" — *incido* = "I cut into / I inscribe")

**Mission:** A privacy-first, on-device note-taking application. All data stays on the user's device by default. Built to be free, offline-capable, and never lock user content behind a vendor.

**Target Audience:** Privacy-conscious users, anyone wanting a Google Keep alternative without cloud dependency, users who want to avoid paid subscriptions for basic note-taking.

**v0.1 Scope (this plan):** Android-only proof-of-concept / Minimum Viable Product. Demonstrates the core architecture, data layer, and UI shell. Sets the technical foundation for all future features without requiring rewrites.

**Tagline (suggested):** *Your notes. Your device. Your terms.*

---

## 1. Licensing

### 1.1 FOSS Flavor — License: AGPL-3.0

- Anyone may use, modify, and redistribute the code.
- Anyone who runs a modified version (even as a network service) **must publish their source code changes**.
- This enforces the "contribute back" requirement for downstream users while still allowing them to profit from their own derivative applications.
- Full license text: https://www.gnu.org/licenses/agpl-3.0.en.html
- A `LICENSE` file containing the full AGPL-3.0 text must be committed to the repository root.
- A `NOTICE` file should credit contributors and reference the license.

### 1.2 Commercial Flavor — Future Feature
A separate commercial build under a proprietary license, intended for users/organizations who want the commercial sync service, premium support, or integration features. Not in v0.1 scope.

---

## 2. Repository & Project Setup

### 2.1 Hosting
- **Host:** Self-hosted Gitea
- **Visibility:** Public (for FOSS community contribution)
- **Repository name suggestion:** `incido`

### 2.2 Package & Identity
- **Application ID:** `org.incido.app`
- **Display name:** Incido
- **License file:** `LICENSE` (AGPL-3.0)
- **Notice file:** `NOTICE`

### 2.3 Local Toolchain Requirements
The following must be installed on the development machine before any build will succeed:

| Tool | Version (recommended) | Purpose |
|------|----------------------|---------|
| JDK | 17 (LTS) | Kotlin/Java compilation |
| Android Studio | Ladybug (2024.2.1) or newer | IDE, SDK management, device deployment |
| Android SDK Platform | API 35 | Compile target |
| Android SDK Build-Tools | 35.0.0 | Build pipeline |
| Android SDK Platform-Tools | Latest | `adb` for device install |
| Kotlin | 2.0.21+ | Language (bundled with Android Studio) |
| Gradle | 8.10+ | Build system (wrapper handles this) |

For a non-developer: Android Studio bundles JDK, Kotlin, Gradle, and the SDK. **Install Android Studio first; everything else follows.**

### 2.4 SDK Levels
- `minSdk = 26` (Android 8.0 Oreo — covers ~95% of active devices)
- `targetSdk = 35` (Android 15)
- `compileSdk = 35`

---

## 3. Architecture & Technology Choices

### 3.1 Language & UI Framework
- **Kotlin** 2.0.21+ as the primary language
- **Jetpack Compose** as the UI framework (Android-recommended; maps cleanly to Compose Multiplatform for future ports)
- **Kotlin Multiplatform (KMP)** with the UI in the **shared module** from day one. This is the core future-proofing decision: when iOS/Desktop ports come later, no UI rewrite is needed.

### 3.2 Build System
- **Gradle 8.10+** with **Kotlin DSL** (`.kts` build files)
- **Version catalog** (`gradle/libs.versions.toml`) — a single source of truth for all library versions. Critical for AI-assisted workflows to avoid version drift.

### 3.3 Module Structure (Multi-Module)
The project is split into the following Gradle modules:

```
incido/
├── app/                          # Android application module (entry point, manifest, MainActivity)
├── composeApp/                   # KMP shared module — UI lives here from day 1
│   └── src/
│       ├── commonMain/           # Shared Kotlin + Compose UI (works on Android, iOS, Desktop)
│       └── androidMain/          # Android-specific glue (Activity host, resources)
├── core/
│   ├── data/                     # KMP shared module — ObjectBox wrapper, repository, models
│   └── domain/                   # KMP shared module — use cases, business logic interfaces
├── gradle/
│   └── libs.versions.toml        # Version catalog (single source of truth)
└── settings.gradle.kts
```

**Why this structure:**
- `core/data` and `core/domain` are pure Kotlin and reusable on iOS/Desktop later.
- `composeApp` is the KMP UI module that all platforms consume.
- `app` is just the Android wrapper (manifest, MainActivity, app icon).
- Adding iOS later = create `iosApp/` module pointing at `composeApp`. Adding Desktop = add `desktopMain` source set.

### 3.4 Data Layer
- **ObjectBox** for persistence
  - Supports KMP shared modules
  - Native blob support for images/audio (future-proofing media storage)
  - Built-in encryption support (for future feature)
  - Vector search capability (future-proofing semantic search)
- **Data model for v0.1:** Single `NoteEntity` with fields:
  - `id: Long` (ObjectBox-managed)
  - `content: String` (the note text)
  - `createdAt: Long` (epoch millis)
  - `updatedAt: Long` (epoch millis)
- **Repository pattern:** `NoteRepository` interface in `core/domain`, ObjectBox-backed implementation in `core/data`. ViewModels consume the interface, not the implementation.

### 3.5 State Management
- **ViewModel + StateFlow** (standard Jetpack pattern)
- Each screen has a single ViewModel exposing immutable UI state as a `StateFlow<UiState>`
- No third-party state management library in v0.1 (Redux/MVI/Compose-Runtime can come later if needed)

### 3.6 Navigation
- **Navigation Compose** (`androidx.navigation:navigation-compose`)
- Two screens in v0.1:
  1. `NoteListScreen` — shows all notes as cards
  2. `NoteEditorScreen` — add/edit a single note

---

## 4. v0.1 Feature Specification

### 4.1 Functional Requirements

| ID | Requirement | Acceptance Criteria |
|----|-------------|---------------------|
| F1 | **List of currently saved notes** | On app launch (and at all times when on the home screen), the user sees a scrollable list of all notes currently stored in the database. Each note is represented as a card showing a preview of its content and its last-updated timestamp. |
| F2 | Create a new note | Tapping "+" opens an empty editor; saving adds the note to the list and database. |
| F3 | Edit an existing note | Tapping a note card opens the editor pre-filled with its content; saving updates the note in place and reflects the change on the list. |
| F4 | Delete a note | A delete action on a note card (or in the editor) removes the note from both the list and the database. |
| F5 | Data persists across restarts | Notes created in one session are visible in the list after force-closing and reopening the app. |
| F6 | Empty state | When the list is empty (no notes saved), show a friendly empty-state message instead of an empty list. |
| F7 | List refreshes automatically | The list of saved notes updates immediately after creating, editing, or deleting a note — no manual reload required. |

### 4.2 Non-Functional Requirements

| ID | Requirement |
|----|-------------|
| N1 | App launches in under 2 seconds on a mid-range device |
| N2 | No network permission required (offline-first) |
| N3 | No analytics, telemetry, or third-party trackers |
| N4 | Single APK, no dynamic feature modules |
| N5 | Dark mode follows system setting (light/dark theming scaffolded for future customization) |

### 4.3 Out of Scope for v0.1 (deferred to future features)
All features listed in §6.

---

## 5. UI/UX Skeleton

### 5.1 Screen 1 — Note List (Home)
- **Purpose:** Display the list of currently saved notes.
- **Top bar:** App title "Incido"
- **Body:**
  - If empty: centered text "No notes yet. Tap + to start."
  - If populated: vertical scroll of `NoteCard` items, newest first
- **Floating Action Button (FAB):** "+" icon, bottom-right, navigates to editor for a new note
- **`NoteCard` design:**
  - Displays the note content (first ~3 lines, truncated)
  - Shows relative timestamp ("2 min ago", "Yesterday", etc.)
  - Whole card is tappable → opens editor for that note
  - Long-press or swipe reveals delete action

### 5.2 Screen 2 — Note Editor
- **Top bar:** Back arrow + Save action
- **Body:** Single multi-line `TextField` filling the screen, auto-focused
- **Behavior:**
  - Back arrow without save = discard (no confirmation in v0.1; v0.2 should confirm if content changed)
  - Save action persists and returns to the list; the updated/created note is visible immediately on the list
  - Delete button (only when editing existing note) at bottom or in top bar overflow

### 5.3 Theming
- **Material 3** (Material You) design system
- **Dynamic color** on Android 12+ (system-derived accent)
- **Light/Dark mode** automatic via system setting
- Brand-neutral palette in v0.1 (custom theming in future)

---

## 6. Future Features (Backlog)

This list is the canonical backlog. Items can be promoted into future versions as the project matures.

### 6.1 Keep Parity
- Rich text formatting (bold, italic, lists, headings)
- Checklists / to-do items within notes
- Color-coded notes and labels
- Pinning notes to top
- Archive (vs. delete) with archive view
- Trash with soft-delete and recovery window
- Full-text search across note content
- Tag / hashtag system with dedicated tag browser
- Search by color, tag, or content
- Reminders / time-based notifications on notes
- Home screen widgets (list widget, quick-capture widget)
- Share-into: receive text/images from other apps
- Drawing / handwritten notes
- Image attachments from camera and gallery
- Audio attachments / voice notes

### 6.2 On-Device Machine Learning
- **OCR (Optical Character Recognition):**
  - Extract text from images attached to notes
  - Handwriting recognition
  - Document scanning with perspective correction
  - Table extraction
- **Speech-to-Text:**
  - Transcription of audio note attachments
  - Live dictation while composing notes
  - Translation
  - Speaker diarization
- **Search index:** automatically index extracted OCR text for full-text search
- ML inference runs entirely on-device (ML Kit, Gemini Nano, or Whisper-tiny)

### 6.3 Cross-Platform Ports
- **iOS** — via Compose Multiplatform (UI already shared)
- **Linux** — Compose Multiplatform Desktop (JVM)
- **Windows** — Compose Multiplatform Desktop (JVM)
- **macOS** — Compose Multiplatform Desktop (JVM)
- Each platform shares `core/data`, `core/domain`, and `composeApp`

### 6.4 Security & Privacy
- ObjectBox database encryption (AES-256 at rest)
- App-lock with PIN
- App-lock with biometric (fingerprint / face)
- Auto-lock timeout
- Encrypted exports
- Secure clipboard handling

### 6.5 Sync & Cloud (Optional, Future)
- Self-hosted sync server (open source, user-runs)
- E2E-encrypted sync protocol
- Multi-device sync
- Optional premium/hosted sync service (Commercial flavor)

### 6.6 Commercial Flavor
- Separate proprietary build under commercial license
- Bundled sync service subscription
- Premium support tier
- Integration APIs for enterprise

### 6.7 Quality of Life
- Markdown rendering and editing
- Import from Google Keep, Evernote, plain text, Markdown files
- Export to plain text, Markdown, PDF, HTML
- Custom themes and color schemes
- Note linking / wiki-style cross-references
- Folders / notebooks in addition to tags
- Versioning / note history
- Undo/redo

### 6.8 Developer / Community
- Continuous Integration via Gitea Actions
- Automated APK builds on commit
- Translation infrastructure (Weblate or Crowdin)
- Contribution guidelines (`CONTRIBUTING.md`)
- Code of conduct
- Issue and PR templates
- Documentation site (public)
- Release/signing infrastructure for Play Store distribution

---

## 7. Build & Verification Plan for v0.1

### 7.1 "Done" Definition for v0.1
v0.1 is considered complete when **all** of the following are true:

1. `./gradlew assembleDebug` succeeds on a clean clone of the repository
2. The generated APK installs on a real Android device via Android Studio's Run button
3. Manual test pass on a real device:
   - App launch shows the list of currently saved notes (empty state on first run)
   - Create 3 notes with different content → all 3 are visible on the list
   - Edit one note → change appears on its card on the list
   - Delete one note → it disappears from the list
   - Force-stop the app, reopen → all remaining notes still appear on the list
4. `README.md` contains:
   - Project description
   - Build instructions
   - Install/run instructions
   - License notice
5. `LICENSE` (AGPL-3.0) is committed
6. `NOTICE` is committed

### 7.2 Manual Smoke Test Script (run before tagging v0.1)
```
[ ] Launch app — see empty state message ("No notes yet. Tap + to start.")
[ ] Tap FAB — editor opens, cursor in text field
[ ] Type "Test note 1" — tap save — returns to list, "Test note 1" card visible
[ ] Repeat for "Test note 2" and "Test note 3"
[ ] Confirm all 3 notes visible on the list, newest at top
[ ] Tap "Test note 2" card — editor opens with existing content
[ ] Change to "Test note 2 (edited)" — tap save
[ ] Confirm updated text appears on the card on the list
[ ] Long-press "Test note 3" — delete option appears
[ ] Confirm delete — note removed from the list
[ ] Force-stop app from system settings
[ ] Reopen app — "Test note 1" and "Test note 2 (edited)" both visible on the list
[ ] Pass — v0.1 verified
```

---

## 8. Development Workflow (for AI-Assisted Building)

Because the developer is not a coder, the following workflow is recommended:

### 8.1 Iteration Loop
1. **State the task in plain English** to the AI coding assistant (e.g., "create the NoteEditorScreen Composable with a single TextField and a save button").
2. **AI writes code** into the appropriate module/file.
3. **AI reports what files were created/modified.**
4. **Developer reviews the diff** in Android Studio or VS Code.
5. **Build via Android Studio** (green Run button) or terminal `./gradlew assembleDebug`.
6. **Install on real device** (Android Studio handles this).
7. **Manual smoke test.**
8. **Commit to Gitea** with a meaningful message.

### 8.2 Recommended Commit Cadence
- Commit after each working milestone (e.g., "scaffold multi-module project", "implement NoteRepository", "build NoteListScreen").
- Use Conventional Commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`.

### 8.3 Where AI Helpers Should Place Code
A short reference for AI assistants:

| What you're building | Where it goes |
|----------------------|---------------|
| Activity / Application class | `app/src/main/kotlin/...` |
| Composables (UI screens) | `composeApp/src/commonMain/kotlin/...` |
| ViewModels | `composeApp/src/commonMain/kotlin/.../viewmodel/` |
| ObjectBox entities | `core/data/src/commonMain/kotlin/.../entity/` |
| Repositories | `core/data/src/commonMain/kotlin/.../repository/` |
| Use cases | `core/domain/src/commonMain/kotlin/.../usecase/` |
| Android-specific resources | `app/src/main/res/` |
| Dependencies | `gradle/libs.versions.toml` (never hardcode versions elsewhere) |

---

## 9. Risks & Open Questions

### 9.1 Known Risks
- **ObjectBox KMP setup is non-trivial** — first-time KMP+ObjectBox configuration may require debugging. Allow extra time for initial build configuration.
- **Compose Multiplatform is mature but Android-first** — minor adjustments may be needed when iOS/Desktop ports happen. Not a v0.1 concern.
- **AGPL-3.0 is strict** — some potential contributors or downstream users may prefer MIT/Apache. This is intentional per requirements; document clearly in README.

### 9.2 Open Questions (to resolve during v0.1 development)
- App icon design — placeholder for v0.1; designed icon in v0.2.
- Splash screen design — Android 12+ splash API; minimal in v0.1.
- ObjectBox license — verify ObjectBox's own license terms are compatible with AGPL-3.0 distribution.
- Play Store distribution — not in v0.1; F-Droid distribution should be evaluated for FOSS flavor.

---

## 10. Document History

> **Version scheme (from v0.3.0.0 onwards):** `MAJOR.MINOR.MAINTENANCE.EMERGENCY` —
> e.g. `0.3.0.0`. `MAJOR.MINOR.MAINTENANCE` are normal release numbers;
> `EMERGENCY` is non-zero only for hotfixes shipped out-of-band.
> `versionCode` is a monotonic int and always +1 per release.
> The build refuses to compile if `versionName` doesn't match this shape.

| Version | Date | Notes |
|---------|------|-------|
| 0.1.0.0 | 2026-08-14 | Initial plan drafted via interview |
| 0.1.1.0 | 2026-08-14 | F1 explicit "list of currently saved notes" requirement + F7 auto-refresh + clarified UI section + editor IME fix (contentWindowInsets + adjustResize) + title/body on cards |
| 0.2.0.0 | 2026-08-14 | Polish + first Keep-parity features. Discard-confirm dialog; release signing config (dev keystore). Favorites (renamed from Pinned Notes), full-text search, 6 colour-coded notes, inline GFM checklists (open/done counts). ObjectBox KMP migration deferred to v0.5 (tracked). |
| 0.2.0.1 | 2026-08-14 | Hotfix: search-active flag folded into uiState so the search icon actually opens the field. |
| 0.3.0.0 | 2026-08-14 | Hashtags (separate entity + cross-ref, 5-tag cap, autocomplete, persistent chips on editor, search() also matches tag names) + bolder colour accent (14 dp gradient stripe + tinted card background + corner chip) + nav drawer (Home / Favorites / Untagged + recent tags) + centred app-bar title + new version scheme adopted (validator in app/build.gradle.kts). |
| 0.3.0.1 | 2026-08-14 | Urgent UI polish: editor hashtag row moved to the bottom (and hidden when empty), `+ add` chip removed (use `#` icon in top bar), colour picker centred horizontally, list-card dog-ear colour accent replaces the small circle chip, list cards show a hashtag row (with `+N` abbreviation when capped). |
| 0.3.0.2 | 2026-08-14 | Hotfix: dropped the redundant leading `#` from the AddTagSheet placeholder (was `#tag-name`, now `hashtag-name` — the leading `#` icon in the field already signals the format). |


---

## Appendix A — Key Library Versions (for the version catalog)

These versions are current as of plan drafting. The AI assistant should verify and pin them in `gradle/libs.versions.toml` at project scaffold time:

| Library | Version | Purpose |
|---------|---------|---------|
| Kotlin | 2.0.21 | Language |
| Compose Multiplatform | 1.7.0 | Cross-platform UI |
| Jetpack Compose BOM | 2024.10.00 | Android UI |
| AndroidX Lifecycle | 2.8.7 | ViewModels, lifecycle |
| AndroidX Navigation Compose | 2.8.4 | Screen navigation |
| AndroidX Activity Compose | 1.9.3 | Activity integration |
| ObjectBox | 4.0.3 | Database |
| Coroutines | 1.9.0 | Async |

(AIs: confirm latest stable versions before scaffolding.)
